<?php
/**
 * Database, image and output cache.
 *
 * @author Martin "DevelX" Jurča
 * @version 2008-02-14
 */
interface Cache {
    /**
     * Constant reffering to the database cache subsystem.
     */
    const DB = 1;

    /**
     * Constant reffering to the image cache subsystem.
     */
    const IMG = 2;

    /**
     * Constant reffering to the output cache subsystem.
     */
    const OUTPUT = 4;


    /**
     * Constant reffering to the all cache subsystems.
     */
    const ALL = 7;

    /**
     * Flushes all cached database data loaded from the specified table.
     * This method should be invoked automatically by the DBDriver in
     * alterTable, dropTable, insert, update and delete methods.
     *
     * @param String $name Name of the table of which data should be erased
     *        from cache.
     * @return boolean True on success, false otherwise.
     */
    public static function flushTable($name);

    /**
     * Check whether the requested query has been cached. If the query has
     * been cached and the cache record is fresh enought (according to the
     * settings), the query returns the cached query result.
     *
     * @param String $table Name of the table from which the data should be
     *        loaded.
     * @param String $query Query to execute by the database in order to load
     *        data.
     * @return mixed Cached query result if the query is stored in cache. If
     *         the query could not be found in the cache, the method returns
     *         false.
     */
    public static function &dbQuery($table, $query);

    /**
     * Saves query result into cache for further usage.
     *
     * @param String $table Name of the table used to select data from the
     *        database.
     * @param String $query Query executed by the database that has been used
     *        to obtain the result.
     * @param mixed $result Result to store in the cache.
     */
    public static function dbSaveQuery($table, $query, &$result);

    /**
     * Starts caching PHP's output into output cache. The output is indexed by
     * $renderOptions and $id. If such output is already in the cache, it is
     * sent to PHP's stadart output. As the the rendered templates are cached
     * instead of whole pages, this provides balance between usability and
     * achievable performance.
     *
     * @param String $id Unique id representing the cached template. Instead
     *        of caching whole pages, only rendered templates themselves
     *        should be cached. Possible syntax for identifying templates
     *        could be: <module>-<template name>, e.g.: Article Manager/view
     * @param Array $renderOptions Optional parameter specifing additional info
     *        required for indexing provided output.
     * @return boolean True if the data was in cache and has been sent to the
     *         standart output. Otherwise returns false and starts to send all
     *         output to selected page cache.
     */
    public static function startOutputCache($id, &$renderOptions = array());

    /**
     * Pauses caching output for selected template, so different template may
     * be cached without colliding with previous one, and after finishing the
     * sub-template rendering, caching of previous template may continue to
     * the end. After pausing the cached data are sent to output so caching of
     * another file may begin.
     *
     * @param String $id See the startPageCache method for more details.
     * @return boolean True on success, false otherwise.
     */
    public static function pauseOutputCache($id);

    /**
     * Continues the previously paused output caching.
     *
     * @param String $id See the startPageCache method for more details.
     * @return boolean True on success, false otherwise.
     */
    public static function continueOutputCache($id);

    /**
     * Ends caching the output for selected template and stores all the cached
     * output. The cached output is also sent to standart output.
     *
     * @param String $id See the startPageCache method for more details.
     * @return boolean True on success, false otherwise.
     */
    public static function endOutputCache($id);

    /**
     * Displays specified module and also adds this routine to cached data
     * so there can be cached parts of pages, usually rendered templates.
     * The typical use in template would be:
     *     {displaymodule module="MyModule" param="" pause="page"}
     * The code inserted in cache would probably look somewhat like this:
     *     <?php
     *        ModuleManager::getModule('MyModule')->display('menu');
     *     ?>
     *
     * @param String $moduleName Name of the module to display.
     * @param mixed $parameters Array, boolean, number, String or any other
     *        data (no objects) that will be passed as a paramter to requested
     *        display method of given module. Must be transformable into php
     *        code.
     * @return boolean True on success, false otherwise.
     */
    public static function useModuleDisplayer($moduleName, &$paramters);

    /**
     * Erases from the cache all cached output for specified module.
     *
     * @param String $moduleName Name of the module of which all cached output
     *        should be erased.
     */
    public static function flushModulePages($moduleName);

    /**
     * Returns image from cache that has been rendered by given paramethers.
     * If image is not present in cache, cache will access rendering proccess
     * to create image and stores it then in the cache for further use and
     * provides the rendered image.
     *
     * @param Array $parameters Array of image rendering parameters that will
     *        be given to the image renderer. This data are also used to index
     *        images within the cache. For more information see the image
     *        renderer.
     * @return String Binary stream representing the image's file contents. If
     *         the image is not in the cache and image rendering fails, the
     *         method returns false.
     */
    public static function &getImage(&$parameters);

    /**
     * Flushes all the data in the selected cache.
     *
     * @param int $which Binary combination of cache type constants (DB, IMG,
     *        OUTPUT), for example DB | OUTPUT will flush both the database
     *        and page cache, yet it keep all the data cached in the image
     *        cache. Special constant ALL_CACHE can be also used to flush all
     *        caches at once.
     * @return boolean True on success, false otherwise.
     */
    public static function flushCache($which);
}
?>
